home *** CD-ROM | disk | FTP | other *** search
/ Giga Games 1 / Giga Games.iso / net / hack / 3_1_3 / sys / vms / install.vms < prev    next >
Encoding:
Text File  |  1993-07-07  |  31.5 KB  |  531 lines
  1.                Instructions for Installing NetHack 3.1.3
  2.                            on a VMS system
  3.                =========================================
  4.  
  5. 0.  Please read this entire file before trying to build or install
  6.     NetHack, then read it again!
  7.  
  8. 1.  Building NetHack requires a C compiler (either VAX C, DEC C, or GNU C)
  9.     and VMS version V4.6 or later (but see note #11).  This release has
  10.     been tested on VAX/VMS V5.5-2, T6.0, and Alpha/VMS V1.0, V1.5.  The build
  11.     procedure (vmsbuild.com) should not need to be modified; it accepts
  12.     an option for selecting VAXC vs GNUC, and it can detect different
  13.     versions of VAXC to use appropriate CC command qualifiers.  Versions
  14.     of VAXC earlier than V2.3 will produce many warning messages (about
  15.     170 per source file; over to 20,000 total!), but NetHack has been
  16.     verified to compile, link, and execute correctly when built with VAXC
  17.     V2.2 using vmsbuild.com.  There is also a set of Makefiles suitable
  18.     for use with MMS; they may or may not work with other make utilities.
  19.  
  20. 2.  Make sure all the NetHack files are in the appropriate directory
  21.     structure.  You should set up a directory--referred to as "top" below
  22.     and in some of the assorted files, but which may be a subdirectory--
  23.     that has these subdirectories
  24.         [.dat]          -- data files
  25.         [.doc]          -- documentation files
  26.         [.include]      -- C header files
  27.         [.src]          -- primary source files
  28.         [.sys]          -- parent for [.sys.*]
  29.         [.sys   .share] -- files shared by several ports, including VMS
  30.         [.sys   .vms]   -- VMS-specific source and support files
  31.         [.util]         -- sources for essential utility programs
  32.         [.win]          -- parent for [.win.*]
  33.         [.win   .tty]   -- "window" routines for ordinary terminals
  34.                            (including terminal windows on workstations)
  35.     The following subdirectories may be present, but are not useful for
  36.     building NetHack on VMS and are not required:
  37.         [.sys   .amiga] -- AmigaDOS
  38.         [.sys   .amiga   .splitter]
  39.         [.sys   .atari] -- Atari TOS
  40.         [.sys   .mac]   -- Macintosh
  41.         [.sys   .msdos] -- MSDOS for IBM PCs and compatibles
  42.         [.sys   .os2]   -- OS/2
  43.         [.sys   .share   .sounds] -- AIFF format audio files
  44.         [.sys   .unix]  -- guess :-)
  45.         [.sys   .winnt] -- Windows NT
  46.         [.win   .X11]   -- window routines for X-Windows; requires X11R4
  47.                            or later and MIT's Athena Widget set
  48.     You must arrange things in this structure or the supplied procedures
  49.     and instructions in this file will not work properly.  Several DCL
  50.     command files are present in the [.sys.vms] subdirectory and won't
  51.     work as intended if they're moved elsewhere.  The file called Files
  52.     in the top directory contains lists of everything that should be in
  53.     each subdirectory, including things that are constructed as NetHack
  54.     is being built.  If you obtain the NetHack distribution via the
  55.     "shar" packaging used for Usenet newsgroup comp.sources.games and its
  56.     archives, you may have to reconstruct several files that were split
  57.     for posting.  At the time of this writing, the list of files needing
  58.     such treatment is not known, so they can't be enumerated here or
  59.     handled automatically be the build procedures.
  60.  
  61. 3.  Prior to beginning compilation, go to the [.include] subdirectory and
  62.     edit vmsconf.h according to its comments.  You should set Local_WIZARD
  63.     and Local_HACKDIR to appropriate values, and you might want to define
  64.     TEXTCOLOR if you have any color VAXstations or color terminals which
  65.     handle ANSI-format escape sequences to set foreground and background
  66.     color for text characters.  (VT241/VT340 color graphics won't work.)
  67.     Other things which may be of interest are SECURE if you intend to
  68.     set up NetHack as an installed image which is granted privileges, and
  69.     SHELL which should be disabled if you intend to allow captive accounts
  70.     to run NetHack.  You may also want to edit file config.h, but that's
  71.     only necessary if you want or need to disable some of the game options.
  72.     The distributed copy of config.h will work successfully on VMS;
  73.     vmsconf.h has conditional code to deal with the UNIX-specific items.
  74.  
  75. 4.  If you have the programming utilities lex or flex and yacc or bison,
  76.     you may edit the procedure [.sys.vms]spec_lev.com and execute it to
  77.     process several source files for NetHack's special level and dungeon
  78.     compilers.  If you don't modify spec_lev.com, it will copy some
  79.     pre-processed versions of the appropriate files (dgn_lex.c, lev_lex.c,
  80.     dgn_yacc.c, lev_yacc.c, dgn_comp.h, and lev_comp.h) from [.sys.share]
  81.     into [.util]*.c and [.include]*.h.
  82.        $ @[.SYS.VMS]SPEC_LEV            ![OPTIONAL]
  83.     If you perform this step, do it prior to executing vmsbuild.com; if
  84.     you don't perform this step, vmsbuild.com will do so for you.
  85.  
  86. 5.  If you are using DEC C (not to be confused with Digital's VAX C) as
  87.     your compiler, you should create an empty file called CRTL.OPT in the
  88.     [.src] subdirectory.  This is a linker options file for accessing
  89.     the C run-time library.  If you don't create it, vmsbuild.com will
  90.     construct one suitable for linking with shareable VAXCRTL.  Programs
  91.     compiled with DEC C should link with DECC$SHR instead; no special
  92.     linker options are needed in that case and VAXCRTL should be avoided.
  93.     You should also create a DCL symbol for invoking CC that specifies
  94.     VAXC compatibility mode.
  95.        $ CC == "CC/Standard=VAXC"
  96.     You might also want to specify /noOptimize if you don't trust the V1
  97.     compiler's optimizer yet.  No other special qualifiers are needed.
  98.  
  99. 6.  To build NETHACK.EXE and its auxiliary programs, execute the
  100.     following DCL command:
  101.        $ @[.SYS.VMS]VMSBUILD    !defaults to VAXC unless symbol 'CC' exists
  102.     or $ @[.SYS.VMS]VMSBUILD "GNUC"
  103.     It can take quite a bit of time for a full build to complete.
  104.     vmsbuild.com will display some feedback as it executes; generally
  105.     this will be the name of each source file that's about to be compiled
  106.     or the name of the executable that has just been linked.
  107.  
  108. 7.  After compilation, it's time to perform installation.  Go back to
  109.     the top directory.  Either edit [.sys.vms]install.com to indicate
  110.     where you want everything to be installed, or specify the location
  111.     and "playground" owner on the command line.  Then execute either
  112.        $ @[.SYS.VMS]INSTALL
  113.     or $ @[.SYS.VMS]INSTALL location owner
  114.     where location is a device:[directory] specification and owner is
  115.     either a rights identifier or UIC.  If install.com is not modified
  116.     and if values aren't supplied on the command line, the default values
  117.     used are the translation of logical name HACKDIR, if any, or else
  118.     [.PLAY] (relative to the current directory), and the UIC for the
  119.     current process.  install.com will use the auxiliary programs
  120.     constructed by vmsbuild.com to process quite a few data files in the
  121.     [.dat] subdirectory.  Then it will create the playground directory,
  122.     if necessary, plus the associated [.save] subdirectory.  Next it will
  123.     copy the data files into the playground; this step can take a while.
  124.     Finally it will copy nethack.exe and a few additional support files.
  125.  
  126.     After it completes, the files [.src]nethack.olb, [.src]nethack.exe,
  127.     [.util]*.obj, [.util]*_comp.exe, and [.util]makedefs.exe can be
  128.     deleted in order to save disk space if desired.  The other program,
  129.     [.util]recover.exe, should not be deleted unless you make a copy of
  130.     it somewhere--perhaps in the playground directory--first.  It can be
  131.     used to resurrect some games disrupted by system or program crash.
  132.  
  133. 8.  The file nethack.com which is copied to the playground directory can
  134.     be used to invoke NetHack, or nethack.exe can be run directly.  Most
  135.     of the command-line options specified in the Unix man-page (file
  136.     [.dat]nethack.6) are also applicable to VMS.  Some comments at the
  137.     beginning of nethack.com illustrate several of the options.  New
  138.     players should read the document file "Guidebook.txt" which will
  139.     be available in the playground directory.
  140.  
  141.  
  142. Notes:
  143.  
  144. 1.  Save files and bones files from earlier versions, including 3.1.2,
  145.     will not work with 3.1.3.  The scoreboard file (RECORD) from 3.1.<any>
  146.     is compatible with 3.1.3, but one from 3.0pl10 or earlier is not.
  147.     When moving an existing scoreboard file into the new playground
  148.     directory, it must end up as file version one (RECORD.;1) or NetHack
  149.     will ignore it.
  150.  
  151. 2.  To specify user-preference options in your environment, define the
  152.     logical name NETHACKOPTIONS to have the value of a quoted string
  153.     containing a comma separated list of option values.  The option names
  154.     are case-insensitive.
  155.        $ define nethackoptions "noAutoPickup,Dog:Rover,Cat:Felix,DECgraphics"
  156.     One value you'll probably want to specify is "noLegacy" to turn off
  157.     the initial introductory passage.  The "checkpoint" option controls
  158.     whether or not enough data is saved to disk so that the set of level
  159.     files left behind after a crash contains sufficient information for
  160.     recover.exe to be able to construct a save file after the fact.  The
  161.     tradeoff for enabling checkpoint is that using it makes level changes
  162.     do more I/O and take longer.
  163.  
  164.     If logical name or DCL symbol NETHACKOPTIONS is not defined, NetHack
  165.     will try HACKOPTIONS instead.  Regardless of whether or not either
  166.     is defined, it will also try to find a configuration file containing
  167.     additional option settings.  If the value of the translation of
  168.     NETHACKOPTIONS--or HACKOPTIONS--begins with an "@" character then the
  169.     rest of the translation is assumed to be the name of the configuration
  170.     file.  Otherwise, the following are tried:  file specified by logical
  171.     name NETHACKINI, file SYS$LOGIN:NETHACK.INI, and file HOME:NETHACK.CNF
  172.     (note that the C run-time library sets up the value of HOME to match
  173.     sys$login).  Syntax for the configuration file is similar to
  174.     NETHACKOPTIONS, but multiple lines can be used, each must start with
  175.     OPTIONS=, and comments can be included by placing '#' in the first
  176.     column.  Several options which take more complex values (graphics
  177.     representation) can also be present; see the "Guidebook" for details.
  178.     (Guidebook.txt can be found in the [.dat] subdirectory; a copy gets
  179.     placed in the playground directory by install.com.  Also, an example
  180.     configuration file can be found in [.win.X11]nethack.rc.)
  181.  
  182. 3.  Instead of using vmsbuild.com to compile and link everything, you can
  183.     use the set of Makefiles found in the vms subdirectory, provided you
  184.     have an appropriate and compatible make utility.  They've been tested
  185.     using Digital's MMS.  There are five of them, and the suffix or
  186.     filetype on their names indicates where they should be placed.
  187.        $ copy [.sys.vms]Makefile.top []Makefile.
  188.        $ copy [.sys.vms]Makefile.src [.src]Makefile.
  189.        $ copy [.sys.vms]Makefile.utl [.util]Makefile.
  190.        $ copy [.sys.vms]Makefile.dat [.dat]Makefile.
  191.        $ copy [.sys.vms]Makefile.doc [.doc]Makefile.
  192.     After doing that, edit [.src]Makefile and [.util]Makefile to specify
  193.     pertinent compiler options in CFLAGS, linker options in LFLAGS, and
  194.     libraries in LIBS and/or MORELIBS if the default values aren't right.
  195.     Be sure to make compatible compilation and linking settings in both
  196.     files.  While in there, edit [.util]Makefile to specify the appropriate
  197.     values for lex and yacc, _or_ move to that directory and use MMS or
  198.     make to build targets no_lex and no_yacc which will copy several
  199.     pre-processed files from [.sys.share] into [.util].  Finally, edit
  200.     Makefile in the top directory to specify values for GAMEDIR and
  201.     GAMEOWNER.  This top Makefile invokes [.sys.vms]install.com to do
  202.     much of the actual installation work, so if you want to make any
  203.     customizations or file protection changes, edit install.com to suit.
  204.     Also set MAKE in all of the Makefiles to the appropriate command if
  205.     not using MMS.
  206.  
  207.     Once the Makefiles are tailored for your site, give the command
  208.        $ mms all,install
  209.     or $ make all install
  210.     To compile and install everything.  The object files compiled via
  211.     the Makefiles are left as individual .OBJ files rather than placed
  212.     into an object library (in contrast to step #7 above and note #12
  213.     below).  These Makefiles are provided on an as-is basis; vmsbuild.com
  214.     is the preferred way to compile because it's guaranteed to compile
  215.     and link everything.
  216.  
  217. 4.  VMS NetHack uses the termcap routines borrowed from GNU Emacs.  These
  218.     have been supplied for those who do not already have GNU Emacs, but
  219.     they are not properly a part of the NetHack distribution.  Since
  220.     these files (gnutermcap.c and gnutparam.c) bear the usual GNU license,
  221.     any executable made with these files is also under the GNU license,
  222.     which among other things means you must be prepared to distribute
  223.     all the source that went into the executable if you distribute the
  224.     executable.  See the GNU license in the files for further details.
  225.     Since NetHack itself has a very similar license, this should not be
  226.     an issue.
  227.  
  228. 5.  termcap is an ASCII data file containing descriptions of terminal
  229.     capabilities and the escape sequences that software must use to take
  230.     advantage of them.  If you do not already have a termcap file in use
  231.     on your system there is a small one in file [.SYS.SHARE]TERMCAP.  It
  232.     contains definitions for common Digital terminals, also suitable for
  233.     most clones and emulators.  This file is copied into the playground
  234.     by install.com, and NetHack will use it if it can't find any other
  235.     one.  NetHack uses the following sequence to attempt to locate the
  236.     termcap file:  translation of the logical name TERMCAP (used as-is),
  237.     file NETHACKDIR:TERMCAP, similar file HACKDIR:TERMCAP, GNU-Emacs file
  238.     EMACS_LIBRARY:[ETC]TERMCAP.DAT, file []TERMCAP, and lastly file
  239.     $TERMCAP (which most likely would be a logical name).  If NetHack
  240.     can't find the termcap file, or if the above search sequence finds a
  241.     different one than you'd prefer, then use the DCL ASSIGN or DEFINE
  242.     command to define a value for logical name TERMCAP.
  243.  
  244.     NetHack also tries fairly hard to figure out what kind of terminal
  245.     you're using.  It checks for logical names (or symbols) NETHACK_TERM,
  246.     HACK_TERM, EMACS_TERM, and lastly TERM.  The last is set up by the
  247.     C run-time library and you cannot use a logical name or symbol for
  248.     it.  If all those fail, or if whichever one succeeds has a value of
  249.     "undefined" or "unknown" (which can happen under VMS V5.4-* and
  250.     V5.5-* for VT420 terminals), NetHack will query the VMS TERMTABLE
  251.     database used by the SMG library routines.  Whatever value NetHack
  252.     eventually comes up with needs to be the name of an entry in the
  253.     termcap file, otherwise a message about "Unknown terminal type" will
  254.     be printed and NetHack will exit.
  255.  
  256. 6.  If you want to use GEM C for cross-compiling from VAX/VMS to Alpha/VMS
  257.     or vice versa, you'll have to build in stages.  For the first pass,
  258.     use a value of CC appropriate for the host system, interactively
  259.     start vmsbuild.com as described in step #6 above, wait until it has
  260.     compiled and linked "makedefs", then use <ctrl/C> to interrupt it
  261.     (after the "12:34 makedefs" feedback message) so that it doesn't
  262.     waste any time compiling the rest of the code.  Consider that to be
  263.     stage 1.  For stage 2, go back to step #5, but set the symbol for
  264.     invoking CC to have a value similar to the following
  265.        $ CC == "GEMC/Standard=VAXC"
  266.     Also set up symbols for cross-architecture access to the linker and
  267.     librarian (these examples assume building an AXP version from a VAX)
  268.        $ LINK == "LINK/Alpha"   !or LINK/VAX
  269.        $ LIBR == "LIBR/Alpha"   !or LIBR/VAX
  270.     Now re-do step #6, but specify "/noExe" as the 4th parameter to
  271.     vmsbuild.com.
  272.        $ @[.SYS.VMS]VMSBUILD "" "" "" "/noExe"
  273.     Note the three empty strings used as placeholders.  That's the end of
  274.     stage 2; everything will be compiled to object files but no executable
  275.     files will have been linked.  If you don't do things this way, a new
  276.     version of makedefs will be linked; but since it will be appropriate
  277.     for the target, vmsbuild's attempt to use it on the host will fail.
  278.     For stage 3, link nethack.exe using vmsbuild.com
  279.        $ @[.SYS.VMS]VMSBUILD "LINK"
  280.     Don't specify "/noExe" this time around or you'll just be wasting
  281.     your time and CPU cycles. ;-)  For stage 4, link all four of the
  282.     utility programs manually (there's no vmsbuild option for this).
  283.     Go to the [.util] subdirectory and issue these commands
  284.        $ LINK makedefs,[-.src]nethack/Lib
  285.        $ LINK/Exe=[]lev_comp lev_main,lev_yacc,lev_lex,panic,[-.src]nethack/Lib
  286.        $ LINK/Exe=[]dgn_comp dgn_main,dgn_yacc,dgn_lex,panic,[-.src]nethack/Lib
  287.        $ LINK recover,[-.src]nethack/Lib
  288.     Note that these commands are slightly simpler than the corresponding
  289.     ones used in vmsbuild.com; crtl.opt is expected to be empty (step #5
  290.     above) so omitted here, and the identification directive is optional.
  291.  
  292.     The installation of the playground (step #7 above) must be done on
  293.     the target system but should need no special cross-architecture
  294.     contortions.
  295.  
  296. 7.  NetHack contains code which attempts to make it secure in case it's
  297.     installed with privileges (to allow the playground to be protected
  298.     against world write access).  This has only undergone limited testing,
  299.     so install NetHack with privileges at your own risk.  If you discover
  300.     any potential security holes, please let us know so that we can take
  301.     steps to correct the problem(s).  NetHack always includes filename
  302.     punctuation when accessing files, so that it should never be affected
  303.     by inadvertent or malicious logical name definitions, and it always
  304.     deactivates installed privileges prior to spawning a subprocess.
  305.  
  306.     Note to end users:  "installing with privileges" is an option for
  307.     system managers who set up system-wide access to the game.  Since
  308.     CMKRNL privilege and modification of the system boot routines are
  309.     both required, it is not an option for ordinary users.  There are
  310.     no explicit instructions on how to do such an installation, because
  311.     only system managers who are already familiar with the process and
  312.     its potential security ramifications should even consider it.
  313.  
  314.     The default setup by install.com assumes no privileges and uses
  315.     world-writable files to allow arbitrary users to play.  This is
  316.     NOT secure and not advisable in any environment where there are
  317.     untrustworthy users, but works fine for many sites.  If you allow
  318.     users to run NetHack from captive accounts (VMS 5.1-* or earlier)
  319.     or from restricted accounts (5.2 and later), you should either make
  320.     sure that they do not have TMPMBX privilege or else disable NetHack's
  321.     ability to spawn an interactive subprocess.  To disable subprocesses,
  322.     disable the "!" (shell escape) command by commenting out the definition
  323.     of SHELL in vmsconf.h prior to building the program.  This necessity
  324.     may be removed in some future release, where NetHack will check for
  325.     captive accounts instead of spawning unconditionally.  Note that
  326.     disabling the SHELL command also prevents spawning MAIL when scrolls
  327.     of new mail are received.
  328.  
  329.     In order for installed privileges to be used at all, the value of
  330.     HACKDIR (via Local_HACKDIR in vmsconf.h) compiled into the program
  331.     must correspond to the actual playground directory.  If logical name
  332.     HACKDIR (or NETHACKDIR) is used to override that value, installed
  333.     privileges will be deactivated unless its value corresponds to the
  334.     same device and directory as the internal value.  If that internal
  335.     value contains a logical name, only an executive-mode translation
  336.     will be honored; if there is no such translation, installed privs
  337.     will be deactivated.
  338.  
  339.     To be able to install nethack.exe with privileges (SYSPRV or GRPPRV,
  340.     perhaps EXQUOTA, depending on site usage and needs), you'll need to
  341.     link it with debugging and tracebacks both disabled.  You can do this
  342.     by specifying an argument to vmsbuild.com when performing step #6
  343.     above; pass it "/noTrace/noDebug" as the 4th parameter.
  344.        $ @[.SYS.VMS]VMSBUILD "" "" "" "/noTrace/noDebug"
  345.     /Trace/noDebug is the linker's normal default.  If you've already
  346.     built NetHack, you can relink with tracebacks disabled by doing
  347.        $ @[.SYS.VMS]VMSBUILD "LINK" "" "" "/noTrace/noDebug"
  348.  
  349. 8.  If you can't or won't install nethack.exe with privileges and if you
  350.     don't have access to a privileged account yourself, then if you intend
  351.     to allow other users to access your copy of NetHack you should probably
  352.     place an ACL on the playground directory and its save subdirectory.
  353.     The access control list should contain a default protection ACE which
  354.     grants delete+control access to the playground owner (ie, your own
  355.     account if there's no special games account involved).  install.com
  356.     does not attempt to do this automatically at the present time.  After
  357.     executing install.com to create the playground directory, perform a
  358.     pair of commands similar to the following
  359.        $ SET ACL/ACL=(IDENT=your_id, OPTIONS=DEFAULT, ACCESS=R+W+E+D+C) -
  360.        $_ device:[playground's.parent.directory]playground.DIR
  361.        $ SET ACL/ACL=(IDENT=your_id, OPTIONS=DEFAULT, ACCESS=R+W+E+D+C) -
  362.        $_ device:[playground.directory]SAVE.DIR
  363.     The two commands use the same options, but SET ACL won't accept a
  364.     list of files to modify.  'your_id' should be the rights identifier
  365.     which corresponds to the account which should retain access to those
  366.     files; 'device:[playground's.parent.directory]' is the name of the
  367.     parent directory for the playground (ie, if your playground directory
  368.     is disk$foo:[me.games.nethack.play], then you want to specify
  369.     disk$foo:[me.games.nethack]play.dir on the SET ACL command), and
  370.     'device:[playground.directory]' is the playground itself.  Those ACLs
  371.     establish a default protection scheme such that every newly created
  372.     file in those directories will have an ACL attached to it, and the
  373.     attached ACL will grant 'your_id' full access to the corresponding
  374.     file.  That should allow you to clear away level files from aborted
  375.     games, and to delete old save files if necessary.  It will not enable
  376.     you to run recover.exe on behalf of other users, because you won't be
  377.     able to create files owned by them unless you have elevated privileges.
  378.  
  379. 9.  Many NetHack commands can be aborted by sending it the <escape>
  380.     character when it wants input.  This is displayed as ESC inside the
  381.     game.  Digital VK201 keyboards (used by VT2xx and VT3xx and older
  382.     VAXstations) and VK401 keyboards (used by VT4xx, newer VAXstations,
  383.     and DEC's X Terminals) do not have an <escape> key.  They may
  384.     transmit <escape> for the <F11> key if the terminal or emulator
  385.     window is set to operate in VT100 mode, or there may be a setup-type
  386.     option for making the <` | ~> key behave as <escape>.  If your
  387.     terminal does not have that, or if it's set to a mode where that
  388.     won't work, then just use <ctrl/[> instead.  (Press the "[" key while
  389.     holding down the "Ctrl" key, then release both; <escape> and <ctrl/[>
  390.     have the same ASCII code and are indistinguishable once they reach
  391.     the computer; note that VAXstations and X Terminals _can_ tell the
  392.     difference, but that won't matter for NetHack.)
  393.  
  394.     VMS NetHack is configured to use the SYS$QIOW system service for
  395.     reading characters from the keyboard.  This allows ^C and ^Y (as well
  396.     as ^X and ^O for wizard mode debugging) to be used as commands without
  397.     being intercepted or interpreted by the terminal driver.  The code
  398.     which parses arrow and function keys is not perfect, and it's possible
  399.     to get strange results if you hold such keys down to just type too
  400.     quickly, particularly on slow multiplexor lines.  Those keys are
  401.     never needed in actual play, and most function keys are just treated
  402.     as <escape> for use in aborting partial commands.
  403.  
  404.     VMS NetHack also still has code to use SMG$READ_KEYSTROKE instead.
  405.     That can be activated by modifying vmsconf.h and recompiling, but
  406.     it should never be necessary.  If you use it, you'll need to press
  407.     either <esc> or <ctrl/[> twice to abort partial commands, or else
  408.     press an arbitrary function key, such as <PF4>, once.
  409.  
  410.     If SUSPEND is defined in vmsconf.h, <ctrl/Z> is used for that command.
  411.     Since Unix-style job control is not available, it's used for connecting
  412.     to the parent process if NetHack is running in a subprocess.  When not
  413.     in a subprocess, it doesn't do anything except give a message to the
  414.     effect that it's not doing anything....  The suspend command does not
  415.     save the current game; if you use ^Z to attach to your parent process,
  416.     be sure to remember to eventually reattach to the NetHack subprocess;
  417.     otherwise the game in progress won't get saved when you logout.
  418.  
  419. 10. NetHack optionally maintains a logfile which receives one line appended
  420.     to it whenever a game ends.  This can be disabled entirely by adding
  421.     an "#undef LOGFILE" directive to vmsconf.h prior to building the
  422.     program, or it can be disabled later by removing the file(s) LOGFILE.;*
  423.     from the playground directory.  If not disabled prior to compilation,
  424.     the logfile can be reinitialized by simply creating an empty file
  425.     named LOGFILE in the playground, but make sure that users are able
  426.     to write into it, or new entries will not be appended.
  427.  
  428. 11. Some attempt at support for VMS versions earlier than V4.6 has been
  429.     included, but no such obsolete system was available for testing it.
  430.     vmsbuild.com detects the need for the extra support routines and
  431.     arranges automatically for them to be compiled.  The reason that
  432.     special support is needed is that the C Run-Time Library (VAXCRTL)
  433.     underwent a major revision for VMS V4.6 and several routines which
  434.     NetHack utilizes were not available prior to that upgrade.
  435.  
  436. 12. vmsbuild.com collects almost all of the object files (xxx.OBJ) into
  437.     an object library (NETHACK.OLB) as it compiles the source files.
  438.     This should prevent the quota-exceeded problems from the linker
  439.     that some sites have reported for prior versions.  Note that if you
  440.     compile any source files manually, you'll need to replace those
  441.     modules in the object library prior to linking the program:
  442.        $ cc/include=[-.include] [-.sys.vms]vmstty   !for example
  443.        $ libr/obj []nethack vmstty                  !replace VMSTTY
  444.        $ @[-.sys.vms]vmsbuild LINK                  !re-link NETHACK.EXE
  445.     If you forget to replace the library entry, your newly compiled code
  446.     will not be included in the new executable image.
  447.  
  448. 13. To access "wizard mode"--intended for debugging purposes, not to
  449.     spoil the game with unlimited wishes--you must be running from the
  450.     username compiled into the game via Local_WIZARD in vmsconf.h, and
  451.     you must specify "-D" on the command line when invoking NetHack.
  452.     Note that it must be uppercase, and it must be in quotes to prevent
  453.     the C run-time library's program startup code from converting it into
  454.     lowercase.  Any character name will be ignored in favor of "wizard".
  455.  
  456. 14. At program startup time, NetHack uses the empty file PERM to prevent
  457.     two different processes from using the same character name (under the
  458.     same UIC ownership) at the same time.  It does this by temporarily
  459.     giving that file a second directory entry named PERM.LOCK, then
  460.     removing the alternate entry once started.  If the PERM file is
  461.     missing or inaccessible, NetHack will give a message and then quit.
  462.     Several possible messages and their usual causes are:
  463.        Can't find file perm;1 to lock!
  464.     PERM.;1 is missing from the playground directory.  Fix:  reinstall
  465.     the playground directory using install.com, or use CREATE or an editor
  466.     to make an empty file named PERM.  Version number must be 1.
  467.        Can't lock perm;1 due to directory protection.
  468.     The playground directory is not allowing write access.  Fix:  players
  469.     need to be able to write files for dungeon levels and "bones" into
  470.     the playground directory.  Set the protection or ACL on the xxx.DIR;1
  471.     file in the playground's parent directory to allow write access.
  472.        Can't unlink perm.lock;1.
  473.     The empty file PERM.;1 is protected against delete access; only matters
  474.     under some versions of VMS.  Fix:  set the protection or ACL on PERM.;1
  475.     to allow delete access to players.  Under VMS V5.5-2, delete access is
  476.     not necessary.  PERM does not have to remain writable.
  477.        Waiting for access to perm;1.  (# retries left).
  478.     If some other process is also starting up NetHack at about the same
  479.     time, you may have to wait a short period.  NetHack will retry once
  480.     per second, counting down to 0.  If 0 is reached, the message
  481.        Perhaps there is an old perm.lock;1 around?
  482.     will be displayed and then NetHack will give up.  Fix:  to forcibly
  483.     remove a stale PERM.LOCK entry, issue the following command
  484.        $ SET FILE/REMOVE PERM.LOCK;1
  485.     from the playground directory.  The file PERM should remain intact.
  486.     Do not use that command for real files, only alternate directory
  487.     entries.  If output from a DIRECTORY command on the playground reports
  488.        PERM.LOCK;1          no such file
  489.     then someone has deleted PERM.;1 while the synonym entry was still
  490.     in place, and PERM.LOCK was left as a dangling name which no longer
  491.     points at any file.  The SET FILE/REMOVE command above will fix it.
  492.  
  493.     In similar fashion, synchronized access to the scoreboard file RECORD
  494.     is accomplished using temporary entry RECORD.LOCK and LOGFILE using
  495.     entry LOGFILE.LOCK.
  496.  
  497. 15. Unless you have both Motif and the Athena Widget set from MIT, you
  498.     will not be able to use the X11 interface on VMS.  Even if you do
  499.     have both those things, such a configuration has not been tested and
  500.     there are no provisions for it in vmsbuild.com.  Makefile.src does
  501.     have the extra source files listed, but not the necessary libraries.
  502.  
  503.     The X11 port will not compile and link with DECwindows, but it will
  504.     be able to display on a VMS DECwindows X server provided that it and
  505.     its Unix X client have a compatible transport between them (either
  506.     TCP/IP added to VMS or DECnet added to Unix) and session security
  507.     is set up appropriately.  You'll need to add the contents of file
  508.     [.win.X11]NetHack.ad into your DECW$USER_DEFAULTS:DECW$XDEFAULTS.DAT,
  509.     and modify some of the lines.  The DECwindows window manager does not
  510.     support having input focus automatically follow the pointer, so you
  511.     should uncomment the "NetHack*autofocus" resource line.  (For Motif
  512.     this may not be necessary, depending on customization options.)
  513.     Uncommenting the "NetHack*slow" line is highly recommended.  You'll
  514.     also need to set "NetHack*fonts: fixed" (rather than "variable"), and
  515.     either set the map font to "fixed" too or install the "nh10" font
  516.     that comes in file [.win.X11]nh10.bdf.  If NetHack warns that the map
  517.     font is variable, then something isn't set up properly.
  518.  
  519.     After creating or modifying decw$xdefaults.dat, you must restart the
  520.     window manager in order for any changes to take effect; it's easiest
  521.     to just make the session manager quit and then log in again.
  522.  
  523. 16. There is no support for VMS POSIX in this release of NetHack.
  524.  
  525. 17. If necessary, send problem reports via e-mail to
  526.        "nethack-bugs@linc.cis.upenn.edu"  (numeric address 130.91.6.8).
  527.     Always include version information for NetHack, the operating system,
  528.     and the C compiler used.
  529.  
  530.  6-JUL-1993
  531.